Most of the spec construction and editing happens in the visual panels to the right. The "Specified" panel is where you edit the Structure Spec, where the "Unspecified" panel gives you a kind of "lookahead" before you add structure to the spec.

The Structure Spec defines a whole lot of rules in a concise visual form. You create and update the spec in the Structure Spec Editor, using mouse actions, toolbar buttons, properties fields, and context menu commands.

As well as expressing rules to guide your team during development, you will use the Structure Spec to make the workspace easier to understand, for instance by adding logical well-named groups and colour.

Visual rules

Rules are expressed in the spec as follows:

Containment.

Any expanded parent (high level folder/folder) should only contain the specified child folders. If child folders are added in the actual codebase without exact equivalents in the spec, they are considered to be violating items and will appear red. When you have an unspecified/red folder, either the code should be made conformant by moving all the files in the folder into folders that are in the spec, or the folder should be added to the spec (right-click/add to spec).

Layering

Unless overridden (right-click/create override), code should only depend on code that is in a lower level in the spec. Upward or sideways dependencies are flagged as violations.

Visibility

You can specify any container item to be private (double-click the visibility property in the cell properties panel, top left), in which case it should only be used by code in sibling containers – non-sibling dependencies are considered violations.

First step, organize your projects

If a Structure Spec hasn’t been created yet, the "Specified" panel will just contain text explaining this. To initialise the spec, click the "+" button on the "Unspecified" panel's toolbar. This will add all your top-level items to the spec, levelized according to their dependencies.

If you have a lot of top-level items (high level folders, folders) it often makes sense to make the top-level architecture easier to understand by organizing your items into groups.

To create a group of items, select a number of them (cmd/ctrl-click) and right-click/create wrapper cell. (“Cells” is what items in the Structure Spec are called).

Once you’ve created wrapper cells, you can drag and drop items in and out of them. You can also adjust the horizontal order and layering of cells by selecting one or more cells and dragging them to a new relative position.

You can give these “wrapper cells” a name in the cell properties panel.

Using the right-click menu, you can re-"levelize" after wrapping or adjusting the levels manually, and set colors for cells. Really useful is the auto-color command, which assigns a separate color to all the children of a selected cell. Auto-color the top level to easily differentiate all your projects. Run auto-color a few times until you get a pallet that looks good to you.

As well as making the workspace easier to understand, you will be starting to specifying dependency constraints between projects by altering the relative layering and visibility. These decisions will cause violations to appear when the source deviates from spec.

At the end of this process, your high level folders may be arranged something like this

:

Next steps, add more specs, top-down

The organization of the top-level-structure into colored groups, with considered layering and visibility, will give the team a great sense of context, particularly when overlayed onto the Structure Map views while coding (using Workspace).

As time goes on, you and your team can extend the Structure Spec deeper into your workspace by adding folders to the spec within the high level folder cells.

Generally you may want to do some work to the codebase structure before locking it into the Structure Spec, for example to remove cyclic dependencies.

Or you might chose to specify the folder layering earlier, as guidance during restructuring activities. How and when you add structure to the Structure Spec depends on the size of your containers, how close they are to a cogent structure, the project priorities, etc.

To add a folder scope to a container that is already in the spec, first select the cell in the spec (it must be a leaf cell, without children yet in the spec). This causes the "Unspecified" panel below to show the contents of the selected container. You can expand/collapse items in the Unspecified panel to expose the new structure that you wish to add to the Spec. Then click the "+" button on the "Unspecified" panel's toolbar. This causes the exposed folders (and any exposed files) to be moved into the spec, as children of the selected item (the "unspecified" panel becomes empty). You can then adjust the layering, grouping, and visibility of the newly-added cells in the spec. By default, any tangle groups are transferred to the spec as "wrapper cells" - which you can rename or remove if you wish.